fix: address external_directory gaps and improve symlink checks #7515

elithrar · 2026-01-09T19:22:25Z

Addresses gaps in the external_directory permission checks where symlinks inside a project could escape to read/write files outside the project boundary.

Add Filesystem.containsResolved() that resolves symlinks before checking path containment, preventing symlink escape attacks where a link like project/escape -> /etc/passwd would bypass lexical checks
Add missing external_directory permission check to WriteTool (was a TODO) and ReadTool
Update File.read() and File.list() to use dual-layer protection: fast lexical check first, then resolved check for existing files
Document TOCTOU limitation in containsResolved() - acceptable for the threat model of protecting against malicious symlinks in user-controlled directories

Test coverage:

Add 17 new tests for containsResolved() covering symlink chains, broken symlinks, relative symlink escapes, and positive cases for internal symlinks
Add integration tests validating File.read() blocks symlink escapes while allowing valid internal symlinks

Validated in practice — I had OpenCode build itself and then test via the actual filesystem as well:

Walk me through the tests, and consider:
- How do you KNOW they are checking symlink traversal correctly?
- Do we have tests that are trivial and not useful for validating symlink traversal and/or external_directory checks?
- Can you build opencode, pass a generate OPENCODE_CONFIG='<config>' with external_directory on/off with `opencode run`, and validate that the implementation solves the issues?

resulted in:

# Set up test scenario with symlink escaping project boundary
mkdir -p /tmp/test/project && cd /tmp/test
echo "SECRET" > secret.txt
ln -s /tmp/test/secret.txt project/escape-link.txt  # symlink points outside
echo "ALLOWED" > project/allowed.txt
cd project && git init && git add . && git commit -m "init"

# Build and run integration test against File.read()
cd packages/opencode && bun run build
bun run -e '
import { File } from "./src/file"
import { Instance } from "./src/project/instance"

await Instance.provide({
  directory: "/tmp/test/project",
  fn: async () => {
    // Should succeed - regular file
    console.log(await File.read("allowed.txt"))  // { content: "ALLOWED" }
    
    // Should throw - symlink escapes project
    await File.read("escape-link.txt")  // "Access denied: path escapes project directory"
  }
})
'

github-actions · 2026-01-09T19:22:36Z

Thanks for your contribution!

This PR doesn't have a linked issue. All PRs must reference an existing issue.

Please:

Open an issue describing the bug/feature (if one doesn't exist)
Add Fixes #<number> or Closes #<number> to this PR description

See CONTRIBUTING.md for details.

github-actions · 2026-01-09T19:22:59Z

The following comment was made by an LLM, it may be inaccurate:

Based on the search results, I found one potentially related PR:

Related PR:

fix: prevent symlink escape in Filesystem.contains #6403: "fix: prevent symlink escape in Filesystem.contains" - fix: prevent symlink escape in Filesystem.contains #6403

This PR appears to address a similar security concern around symlink escapes in path containment checks, which is directly relevant to the current PR's focus on preventing symlink escape attacks.

The current PR (7515) builds upon or may supersede this work by introducing the Filesystem.containsResolved() method and adding missing permission checks to WriteTool and ReadTool.

rmk40 · 2026-01-12T23:14:32Z

This approach makes sense for catching accidental escapes, but it doesn't account for symlinks that are intentionally placed in a project:

~/projects/myproject/
  shared -> ~/shared-libs/        # shared code across projects
  config -> ~/.config/myapp/      # user config
  vendor -> /opt/vendor-sdk/      # vendor SDK

With this change, accessing any of these would trigger a permission prompt every time, even though they're deliberately there.

Could this be configurable instead? Something like:

{
  "permission": {
    "follow_symlinks": "allow",
    "external_directory": {
      "~/shared-libs/*": "allow",
      "*": "ask"
    }
  }
}

Or if a symlink's resolved target already matches an external_directory allow rule, skip the prompt.

That way users who want strict behavior can keep it, while others can explicitly permit symlinks they've set up intentionally.

rekram1-node · 2026-01-13T06:51:27Z

@rmk40 yeah that's a good point, let me ask Dax

- Add Filesystem.containsResolved() that resolves symlinks before checking path containment, preventing symlink escape attacks - Add external_directory permission check to write.ts (was a TODO) - Update File.read/File.list to use containsResolved for existing files - Add dual-layer protection: lexical check first, then resolved check for existing paths - Document TOCTOU limitation in function docstring - Improve test robustness: explicit skip for unsupported symlink operations - Add comprehensive tests for symlink traversal scenarios

Unit tests for Filesystem.contains() and containsResolved() are in test/util/filesystem.test.ts - no need to duplicate in path-traversal.test.ts

ReadTool was missing the containsResolved() check that WriteTool and File.read() have. This meant a symlink inside the project pointing outside could bypass external_directory permission when using ReadTool.

…ypass - Add containsResolved() check to EditTool and PatchTool to prevent symlink escape attacks - Add bypassCwdCheck flag to write.ts for consistency with read.ts - Fix broken symlink bypass: check symlinks BEFORE exists() check so broken symlinks pointing outside are caught - Reorder read.ts to check symlinks before exists() for consistency

- Add 4 symlink tests to ReadTool: escape, broken escape, internal symlink - Create write.test.ts with 7 tests including 4 symlink tests - Tests verify external_directory permission is requested for symlink escapes - Tests verify broken symlinks pointing outside are caught

rekram1-node · 2026-01-13T16:39:51Z

Hm Dax says that symlinks to files outside cwd are okay

elithrar · 2026-01-13T18:31:43Z

updated this.

@rekram1-node @thdxr - I don't entirely agree with the premise that you should (by default) follow symlinks outside of the current working dir.

If your tools (e.g. bash) can be coerced (or discover themselves) into creating a symlink to an external directory outside of cwd you no longer have trust that OpenCode is constrained to the cwd. Is external_directory just a suggestion or is the design goal to actually enforce the agent only works within the current dir?

current state - IMO 1 + 2 are at odds with each other here as allowing 1 is just a different version of 2.

symlinks are now allowed by default - Symlinks inside the project that point to files or directories outside are followed without prompting for external_directory permission.
path traversal is still blocked - Paths containing ../ sequences that would escape the project directory are rejected.
explicit external paths still require permission - Absolute paths outside the project (e.g., /etc/passwd or ~/other-project/file.txt) continue to trigger the external_directory permission prompt.

thdxr · 2026-01-13T18:53:42Z

maybe i'm not following but we know users have a ./tmp/ style folder where they have symlinks to other projects they've cloned to use as reference

this would cause a prompt on those right?

elithrar · 2026-01-13T19:03:49Z

@thdxr yes, but what's the alternative? how you discern between explicit user intent (this ./tmp/*) pattern vs. constraining OpenCode to work in the directory it's intended to?

want to be spammed by permissions prompts as little as the next guy, but I don't get how OpenCode can determine whether following ./tmp/some-project out to /Users/matt/repos/some-project is safe or not out of the box?

do those cases exist because the permissions model was all or nothing prior to the object syntax in permissions?

github-actions bot added the needs:issue label Jan 9, 2026

github-actions bot mentioned this pull request Jan 11, 2026

fix: harden explore agent permissions and bash tool validation #7881

Closed

github-actions bot mentioned this pull request Jan 13, 2026

fix: don't ask for permission for cd within project #8190

Draft

elithrar added 5 commits January 13, 2026 11:30

test: remove duplicate Filesystem.contains tests

06482b0

Unit tests for Filesystem.contains() and containsResolved() are in test/util/filesystem.test.ts - no need to duplicate in path-traversal.test.ts

fix: add symlink resolution check to ReadTool

91f7431

ReadTool was missing the containsResolved() check that WriteTool and File.read() have. This meant a symlink inside the project pointing outside could bypass external_directory permission when using ReadTool.

elithrar force-pushed the improve-ext-dir-checks-symlinks branch from b5c59a5 to c2cc7ac Compare January 13, 2026 16:36

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: address external_directory gaps and improve symlink checks #7515

fix: address external_directory gaps and improve symlink checks #7515

elithrar commented Jan 9, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Jan 9, 2026

Uh oh!

github-actions bot commented Jan 9, 2026

Uh oh!

rmk40 commented Jan 12, 2026

Uh oh!

rekram1-node commented Jan 13, 2026

Uh oh!

rekram1-node commented Jan 13, 2026

Uh oh!

elithrar commented Jan 13, 2026 •

edited

Loading

Uh oh!

thdxr commented Jan 13, 2026

Uh oh!

elithrar commented Jan 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

fix: address external_directory gaps and improve symlink checks #7515

Are you sure you want to change the base?

fix: address external_directory gaps and improve symlink checks #7515

Conversation

elithrar commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 9, 2026

Uh oh!

github-actions bot commented Jan 9, 2026

Uh oh!

rmk40 commented Jan 12, 2026

Uh oh!

rekram1-node commented Jan 13, 2026

Uh oh!

rekram1-node commented Jan 13, 2026

Uh oh!

elithrar commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thdxr commented Jan 13, 2026

Uh oh!

elithrar commented Jan 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

elithrar commented Jan 9, 2026 •

edited

Loading

elithrar commented Jan 13, 2026 •

edited

Loading